
***  This is not a supported program and it is supplied ***
***  AS-IS for official support personnel only          ***

--------------------------------------------------------------------------------
Overview
--------------------------------------------------------------------------------

The HMC Diagnostic tool is intended to find common configuration and
setup errors found between pSeries HMC and Regatta LPARs.

On the whole, it looks for things that will cause RMC communications
to fail. This includes checking for active daemons, correct THL files,
correct ACL files, and (optionally) consistent hostname resolution
between machines. It does this automatically and reports all found
errors.

To be most affective though, the tool needs to collect data from the
LPARs. To do this, it uses rexec from the HMC to the LPAR and it
invokes a copy of itself on the LPAR. This implies two things:

	-rexec is setup between the HMC and the LPAR
	-The tool is installed on the HMC and the LPAR

However, it is not required to use the tool in this fashion, but
running tests on a single machine only is less useful and does not
check for the most common setup problems, ie, consistent hostname
resolution.

The tool will (when appropriate) suggest corrective actions to take to
fix found problems. You can also have the tool perform these actions
for you, but its suggested that you don't use this option until you are
a bit more familiar with this tool (the default is to simply suggest
actions but not take any actions).

--------------------------------------------------------------------------------
Disclaimers
--------------------------------------------------------------------------------
This tool is currently at the alpha release stage. It probably has a
few problems, especially when testing on differing levels of AIX and
HMC (since I developed it on AIX 5.2 and a GA3 HMC almost
exclusively). 

The script is designed for AIX 5.1F/5.2 or better. It may run
on prior levels, but it will probably generate false messages.

I have taken a lot of care so that the tool has no side
effects. Unless directed to, it has no trace files. It only runs
commands that I consider "read only" commands, with one exception. It
will run "refresh -s ctrmc" to validate the ctrmc.acls file, but this
command results in ctrmc re-reading the file. This may have some side
effect, though I would expect in most cases, this is a very minor
issue.

It certainly will not catch all errors, so its entirely possible that
the tool will not find anything wrong, yet things are still not
working. Alternately, it may find problems that don't exist. While I
try to minimize these false messages, they can come up.

Moral : its not a panacea - you must still know how things work...

--------------------------------------------------------------------------------
Usage
--------------------------------------------------------------------------------

To get a "usage" message from the tool itself, give it a bogus command line option:

For example, 

	DiagnoseHMC --help

will produce the usage summary.


Example 1: Test the local machines setup

1) Get command-line access on the machine as user root.  
2) Invoke the script like so:

	DiagnoseHMC

Example 2: How to use the tool to test the HMC setup and validate with LPARs setup

1) Get command-line access to the HMC as user root.  
2) Ensure rexec is enabled from the HMC to the LPAR. (The HMC gui has a way to
	do this). You should be able to run this command on the HMC without being
	prompted for a username and password:

		REXEC_USER=root REXEC_PASS=<roots password on LPAR> rexec <LPAR Hostname> ls

3) Invoke the script (as root) on the HMC like so:

     DiagnoseHMC --target=<LPAR Hostname> --password=<roots password on target>

   To provide multiple targets, use quotes and separate them with a comma:

     DiagnoseHMC --target="lpar1, lpar2, lpar3" --password=<roots password on *all* targets>

--------------------------------------------------------------------------------
Known problems / future work
--------------------------------------------------------------------------------
Basic NLS support is present. Each sub-command exports "LC_ALL=C" so
the output should now be parsable by the script even if the default
locale is something other than C. I have not tested this feature too
much - let me know how it goes.

The output can be a bit too wordy and ugly looking.








